(the first part is in another file: sorry, but this documentation was becoming bigger than SimpleText can handle)
Instructions: Macintosh side
If you are using System 7 and are satisfied by short descriptions of the commands, turn on balloon help; otherwise, read here.
Well, everything depends on what you want to do with suntar. If you need only its encoding/decoding features, you should read only the explanation of Encode and Decode, and know that suntar supports drag&drop (equivalent to Decode with automatic recognition of the file format): or just select the menu items and see what happens.
For exchanging data with UNIX machines through floppy disks, the usual way to begin to work is by inserting a disk: suntar realizes that it's neither a Mac nor a MS-DOS disk and "opens" it for itself. Otherwise, you may select a command (e.g. List) and suntar will ask you to insert a disk, inconditionally opening it as a tar/bar archive. Or you may open the device and then insert the disk.
For other devices (e.g. tapes) you must use the Open Device command, which offers a list of what is available. You should read the documentation about tapes, given in another file.
The first command in the File menu is "Get file info", it may be used to get informations about any file, but it's more useful for files which suntar can open.
Then there is the usual Open, but its use is not usual: it performs some operations which are not essential for suntar but may be useful. You may open a tar or bar archive which is stored in a Macintosh file on a Macintosh volume, or convert files in one of the following formats: MacBinary, BinHex 4.0, ASCII (UNIX or MS-DOS), uuencode and PackIt (even compressed PackIt archives, but not encrypted ones). Suntar automatically recognizes the file format, and that should be good in most cases, but you may change that by a click (unless you've used the drag&drop feature of System 7, so avoiding the dialog).
You may open files by drag&drop, and the behaviour is sometimes different from Open: the destination folder is selected only once and a non-converted file may be copied.
Open device allows you to open a device driver or a SCSI device, optionally specifying a sector where List and Extract should find a tar archive. See the separate file for more informations.
New archive and encode… well, obviously they do the opposite of Open, creating encoded files.
The Eject command may be used when you no more need the disk, but most commands eject the disk when finished. The usual command-shift-1 and command-shift-2 still eject the disk, but suntar might not realize that the disk is no more there: use Eject or its shortcut command-W instead. If a file or device is open, that same item is renamed to become the usual "Close".
Drive list prints some informations about the devices connected to your Mac: you should examine them carefully before trying to use "Open device".
Copy disk archive to file copies all data found on a disk to a Mac file in the tar or bar format; for multi-volume archives, the extra volume headers on disks other than the first one are skipped, so you get a single-volume archive, but no other data conversion is performed.
List prints the list of the files in the tar or bar archive.
"Extract and convert" is the most useful command and the most frequently used (unless you only use Encode and Decode). It reads files from the tar or bar archive and saves them on the Macintosh. However, Macintosh files are different from UNIX files: they are composed of two parts (the data and resource forks) and their attributes are essential (you can't execute an application if its type is not 'APPL', nor extract a StuffIt archive if it's not 'SIT!'); even pure text files are different, using CR rather than LF (see above). To make things easy, suntar recognizes the most common file formats and automatically converts them to the Macintosh form. That includes pure text files and the two formats used by public domain archives, MacBinary (in three variants) and BinHex (.hqx files); in most cases, you get exactly what you want without having to worry about which conversions must be done. When you don't get what you want you may use the options (Preferences menu) to tell suntar what you want.
"Extract selected files" is like Extract, but allows you to choose which file must be extracted from a scrollable list. A "Find" button allows you to select names containing a given string (for example, if you want to extract all .c and .h files, just use Find twice with those strings).
A note for POSIX tar users (e.g. AIX users): usually suntar allows you to insert any disk of the archive, but that's impossible with the POSIX format. Hence, to extract selected files from the second disk you must insert the first disk, click on the Extract button when no file is selected, then insert the second disk. You must have set the "tar version" option to POSIX, otherwise suntar will not ask for the second disk.
Initialize is like the Initialize command in the Finder, but disks which do not support 1440 Kbytes (have no hole...) are formatted at 720K, a format more suitable to exchange data with UNIX machines; if the relative option is set they are initialized in a way that is completely Finder compatible.
Pause and Abort are what you expect, but you'll be surprised to find them in a menu, in most programs they are missing or are buttons. Well, suntar allows you to pull down menus even when it's working, even when it's performing very low level operations, directly talking to device drivers. That can be very useful, and working in background saves time, but it may be dangerous: as any UNIX application, suntar knows only a drive number, not a disk name: if you eject the tar disk from outside suntar (or you use command shift-1, or the Finder ejects it with its usual change disk dialog or the Eject button in the standard file dialog) and insert a Macintosh disk, suntar might not notice the difference, and if you do that while suntar was writing and the second disk contains the only copy of your most precious data... Well, suntar 2.0 tries to avoid that by comparing sector 0 of the disk currently in the drive with a stored copy of what it should be: for the sake of speed that operation is performed at some critical points, not always, so to be safe you should pause suntar before ejecting its disk: when it's in foreground suntar accepts a disk insertion in the open drive and reopens that disk (or exits from a pause) only if sector 0 matches.
In the Write menu, the two Create commands allow you to start a new archive on a floppy disk (or any device is open), overwriting anything was previously on the disk (in Mac style, you may get a few warnings before loosing any data; in order to reduce unintentional data loss, suntar writes any volume header only after you choose the first file to be written). A checkbox allows you to examine the disk (accepting it even if it's write protected) and have an opportunity to eject it before any data is written to it, that's useful for disks following the first one when clicking on "Cancel" to abort the current command is not harmless.
Append is similar but preserves the current contents of the tar/bar archive, adding new files after the existing ones (POSIX tar users must insert all the disks of multi-volume archives, GNU tar and bar users must insert only the last one).
Anyhow, when you are in write mode you select commands in the Write menu and the familiar standard file dialog appears: the "Write folder" button allows you to select whole folders, the Write selected files button transfers the file list into a dialog which allows multiple selections and has a Find button. Choose End of write (or Eject or Abort or Quit) when you have finished.
Files can be written in three different formats: MacBinary saves all the data of a Mac file (using the MacBinary II format, which can be read also by programs which know only about the original MacBinary), ASCII saves the data fork only converting any CR to LF, Data fork only must be used for files already in UNIX format. Mixed write DF/MB tries to choose automatically the correct format (ASCII for text files, MacBinary if there is a resource fork, else Data fork (DF) or MacBinary (MB): e.g. a GIF file or a StuffIt archive will be saved as data fork from Mixed/DF or MacBinary from Mixed/MB, an application as MacBinary from both). Lastly, write tar (or bar) file does the reverse of Copy disk archive to file, appending the contents of the tar (or bar) file to the archive, without any conversion.
At any time you may change the preferences settings, to become active at next file (a good moment to do that is during the confirm saves dialog), or resize the window.
Similarly, you may select any enabled command during semimodal dialogs: you may do anything while they are out, including switching to another task, aborting the current command, moving the dialog and (by holding down the command key, as usual for non-front windows) moving the console window, but you can't hide one of them behind the console (Apple calls them "movable modal dialogs" and gives them a different look, but suntar's implementation was born before System 7 and we never adopted the standard look).
In the Preferences menu, the items in the central section are saved when you quit, the other items are "temporary only" and are reset to their initial state when suntar is launched.
Options calls the options box: use the balloon help for options which are not obvious. Anyway, only two options are essential (you should always assign them !): tar version (it tells suntar what to do about multivolume archives) and "text files creator": it's a four characters string which determines the icon of plain text files and the program which is launched when you double click them (EDIT for the Consulair Edit or its "compatible" Edit II, ttxt for TeachText or SimpleText, MACA for MacWrite… you may use Get File Info to discover the string for your favourite editor, Copy the string from the console and Paste it in the options box). A button brings you into a dialog which assigns type and creator to files with a specific extension: e.g. the default setting assigns .jpg files to JPEG View and .Z files to MacCompress, but you may change that and add other types: use Get file info on a file having the icon which you wish and copy the type&creator strings to the options dialog.
Other options are explained by balloon help. There is a time zone (that of the UNIX machine, since the dates in the tar header are all in Greenwich time), a Mac-to-Mac backup (save as many informations as possible, including those which are meaningful only on a Mac) and Prefs file in Preference folder (I hate those applications which create a file in the Preferences folder the first time they are launched, even if I launch them only once to see whether I like them, so you may choose to create one or keep preferences inside the application itself).
Other rarely used options (buffer sizes, background priority, uid, gid...) may be changed only in expert mode (see later).
A new addition of suntar 2.1 is "Ask the user about": when suntar finds something unusual it usually asks what to do, but since that may be annoying, you may tell it to behave in a fixed way.
The ".hqx prefs" submenu is useful if you often download BinHex files. The problem with such files is that they are plain text files. That's good since they may be sent as E-mail and transferred also in the default mode of ftp, without switching to binary mode, but it's bad since they can be, and usually are, edited before arriving at you. So, they may contain extra text or be incomplete: you may disable conversions if suntar fails to extract them and you wish to try again with a specific program. Usually, before the BinHex data there is some text: sometimes it's the only user manual for the application or INIT in the file (and an INIT has no about box and no menus...), other times it's totally useless; so you may want to save that text in a file, or see it on the console, or simply skip it.
English selects the language of messages (Italian or English, the default depends on the national version of your System file).
"Confirm saves" is used during an "Extract and convert" and allows you to extract only some files from an archive: it is a three-state item, clicking on the buttons "Skip all" or "Save all" puts it in a temporary state, you may return to the normal state by choosing it again.
Select Expert mode and suntar will show some new preferences and a new menu: in this "Special" menu "Create log file" opens a file containing everything was printed to the console (and suntar becomes more verbose to make that text more clear). "Extract at sector" is useful when for any reason suntar refuses to extract a file. "Extract starting from sector" is an extraction from there to the end of the archive. Mac-ize and IBM-ize place an empty filesystem on the disk, useful to return a tar disk to regular use without reformatting it. (Note: fast Macize is a routine written by us, which writes directly to the disk and does not call the Apple initialization routine. It's faster because it does not check the disk for bad sectors).
"Find headers" is essentially a "find all files, including lost and deleted ones", "Read tar at sector" (or Extract from sector) recovers them, see balloon help for the other commands. Anyway, since MacTools, the Norton Utilities, the freeware FLUT and other disk utilities will not recognize a tar disk, it's reassuring to know that suntar has some undelete capabilities for disks which crashed or were partly overwritten.
And, as I told you, once I happened to have a SyQuest cartridge which refused to mount: sector 2 of the HFS partition had been lost (sector 2, the one beginning with 'BD', is essential for mounting a disk). But I know that the sector before the last one contains a copy of what that sector was at the end of the volume initialization: I used Save sectors to copy it to my hard disk, Overwrite sectors to place it back in sector 2 of the HFS partition, and the cartridge was live again: now Norton reported an incorrect number of free allocation blocks (the old sector 2 obviously said that all the disk was free), but that's a minor problem, quickly fixed, since that number is used only for reporting the information to the user. So, that was easy, but Norton Utilities, MacTools, Public Utilities and Disk First Aid could not guess what had to be done, and I do not know any utility which, as suntar, can read and write sectors in a disk which is currently not mounted. It's dangerous: with the same ease I might have destroyed a good disk. But as far as I know suntar is the only utility which could allow me to resurrect that disk.
